Crate safe_transmute

Expand description

This crate contains checked implementations of transmute().

The base functions in this crate are not inherently safe, but just guarded against common simple mistakes (like trying to create an 8-byte type from 7 bytes). These functions are exactly as safe as the data passed to them - creating a null pointer, for example, is not unsafe in and of itself, but dereferencing it certainly is, but they don’t do that (see here for extended discussion).

Other functions in this crate, on the other hand, provide enough safety measures to ensure safety in all circumstances. This is the case for those found in the pod and bool modules.

Take note, however, that alignment is unaccounted for: you may, in the course of using this crate, invoke unaligned access, which some CPUs may trap on; that did not, however, happen in any of our tests on MIPS64 (BE), x86_64 (LE), nor armv6l (LE).

This crate can be used in a no-std environment by disabling the std feature through specifying default-features = false on import.

Examples

View bytes as a series of u16s:

assert_eq!(guarded_transmute_many::<u16>(&[0x00, 0x01,
                                           0x12, 0x34,
                                           // Spare byte, unused
                                           0x00])?,
           &[0x0100, 0x3412]);

View all bytes as a series of u16s:

assert_eq!(guarded_transmute_many_pedantic::<u16>(&[0x00, 0x01,
                                                    0x12, 0x34])?,
           &[0x0100, 0x3412]);

View bytes as an f64:

assert_eq!(guarded_transmute::<f64>(&[0x00, 0x00, 0x00, 0x00,
                                      0x00, 0x00, 0x00, 0x40])?,
           2.0);

View a series of u16s as bytes:

assert_eq!(guarded_transmute_to_bytes_pod_many(&[0x0001u16,
                                                 0x1234u16]),
           &[0x01, 0x00, 0x34, 0x12].le_to_native::<u16>());

Modules

The guard module exposes an API for memory boundary checking.

Module containing various utility functions.

Structs

A slice boundary guard error, usually created by a Guard.

Enums

A transmutation error. This type describes possible errors originating from operations in this crate.

How the type’s size compares to the received byte count and the transmutation function’s characteristic.

Traits

PodTransmutable

Type that can be non-unsafely transmuted into

Functions

guarded_transmute^⚠

Transmute a byte slice into a single instance of a Copyable type.

guarded_transmute_bool_pedantic

View a byte slice as a slice of boolean values.

guarded_transmute_bool_permissive

View a byte slice as a slice of boolean values.

guarded_transmute_bool_vec_pedantic

Transform a byte vector into a vector of bool.

guarded_transmute_bool_vec_permissive

Trasform a byte vector into a vector of bool.

guarded_transmute_many^⚠

View a byte slice as a slice of an arbitrary type.

guarded_transmute_many_pedantic^⚠

View a byte slice as a slice of an arbitrary type.

guarded_transmute_many_permissive^⚠

View a byte slice as a slice of an arbitrary type.

guarded_transmute_pedantic^⚠

Transmute a byte slice into a single instance of a Copyable type.

guarded_transmute_pod

Transmute a byte slice into a single instance of a POD.

guarded_transmute_pod_many

Transmute a byte slice into a single instance of a POD.

guarded_transmute_pod_many_pedantic

View a byte slice as a slice of POD.

guarded_transmute_pod_many_permissive

View a byte slice as a slice of a POD type.

guarded_transmute_pod_pedantic

Transmute a byte slice into a single instance of a POD.

guarded_transmute_pod_vec

Trasform a byte vector into a vector of POD.

guarded_transmute_pod_vec_pedantic

Trasform a byte vector into a vector of POD.

guarded_transmute_pod_vec_permissive

Trasform a byte vector into a vector of POD.

guarded_transmute_to_bytes^⚠

Transmute a single instance of an arbitrary type into a slice of its bytes.

guarded_transmute_to_bytes_many^⚠

Transmute a slice of arbitrary types into a slice of their bytes.

guarded_transmute_to_bytes_pod

Transmute a single instance of a POD type into a slice of its bytes.

guarded_transmute_to_bytes_pod_many

Transmute a slice of arbitrary types into a slice of their bytes.

guarded_transmute_to_bytes_pod_vec

Transmute a vector of POD types into a vector of their bytes, using the same memory buffer as the former.

guarded_transmute_to_bytes_vec^⚠

Transmute a vector of arbitrary types into a vector of their bytes, using the same memory buffer as the former.

guarded_transmute_vec^⚠

Trasform a byte vector into a vector of an arbitrary type.

guarded_transmute_vec_pedantic^⚠

Trasform a byte vector into a vector of an arbitrary type.

guarded_transmute_vec_permissive^⚠

Trasform a byte vector into a vector of an arbitrary type.